/*
*    Qizx/open 3.0 beta
*
* This code is the open-source version of Qizx.
* Copyright (C) 2004-2009 Axyana Software -- All rights reserved.
*
* The contents of this file are subject to the Mozilla Public License 
*  Version 1.1 (the "License"); you may not use this file except in 
*  compliance with the License. You may obtain a copy of the License at
*  http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS" basis,
*  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
*  for the specific language governing rights and limitations under the
*  License.
*
* The Initial Developer of the Original Code is Xavier Franc - Axyana Software.
*
*/
using System;
using System.Qizx.Xml;
namespace System.Qizx.Api
{
	
	/// <summary> Creates Items and related resources (ItemTypes and QNames).</summary>
	public interface ItemFactory
	{
		/// <summary> Returns a QName without namespace and without prefix.</summary>
		/// <param name="localName">a name without colon.
		/// </param>
		/// <returns> a QName instance
		/// </returns>
		QName GetQName(string localName);
		
		/// <summary> Returns a QName without prefix.</summary>
		/// <param name="localName">a name without colon.
		/// </param>
		/// <param name="namespaceURI">namespace URI
		/// </param>
		/// <returns> a QName instance
		/// </returns>
		QName GetQName(string localName, string namespaceURI);
		
		/// <summary> Returns a QName with prefix.</summary>
		/// <param name="localName">a simple name without colon
		/// </param>
		/// <param name="namespaceURI">namespace URI
		/// </param>
		/// <param name="prefix">optional prefix, can be null.
		/// </param>
		/// <returns> a QName instance
		/// </returns>
		QName GetQName(string localName, string namespaceURI, string prefix);
		
		/// <summary> Returns a predefined item Type from its name.
		/// <p>
		/// The name may be a short name without the "xs:" prefix. For example
		/// getType("xs:double") and getType("double") both return a representation
		/// of the XQuery type xs:double.
		/// </summary>
		/// <param name="name">type name. Predefined short names: ENTITY, ID,
		/// IDREF, NCName, NMTOKEN, NOTATION, Name, QName, anyAtomicType,
		/// anySimpleType (item), anyURI, base64Binary, boolean, byte, date,
		/// dateTime, dayTimeDuration, decimal, double, duration, empty,
		/// float, gDay, gMonth, gMonthDay, gYear, gYearMonth, hexBinary,
		/// int, integer, language, long, negativeInteger, node,
		/// nonNegativeInteger, nonPositiveInteger, normalizedString,
		/// positiveInteger, short, string, time, token, unsignedByte,
		/// unsignedInt, unsignedLong, unsignedShort, untypedAtomic,
		/// yearMonthDuration
		/// </param>
		/// <returns> a representation of an XQuery item type
		/// </returns>
		ItemType GetType(string name);
		
		/// <summary> Creates an item from a given object according to the general Java to
		/// XQuery type mapping, also used in the Java Binding extension.
		/// 
		/// </summary>
		/// <param name="value">any object that can be converted to a XQuery Item.
		/// </param>
		/// <param name="type">type of the created item. Can be null. If it is null, the
		/// type will be the "natural type" of the actual object (see the
		/// Java to XQuery Mapping specification in the Qizx documentation).
		/// </param>
		/// <returns> a new Item of the specified type.
		/// </returns>
		/// <throws>  EvaluationException if the conversion was not possible. </throws>
		Item CreateItem(System.Object value_Renamed, ItemType type);
		
		/// <summary> Creates an Item of type xs:boolean.</summary>
		/// <param name="value">a boolean value
		/// </param>
		/// <returns> an Item of type xs:boolean
		/// </returns>
		Item CreateItem(bool value_Renamed);
		
		/// <summary> Creates an Item of type xs:double.</summary>
		/// <param name="value">a double value
		/// </param>
		/// <returns> an Item of type xs:double
		/// </returns>
		Item CreateItem(double value_Renamed);
		
		/// <summary> Creates an Item of type xs:float.</summary>
		/// <param name="value">a float value
		/// </param>
		/// <returns> an Item of type xs:float
		/// </returns>
		Item CreateItem(float value_Renamed);
		
		/// <summary> Creates an Item of type xs:integer, or one of its sub-types. If not
		/// specified (null), the type is xs:integer.
		/// 
		/// </summary>
		/// <param name="value">any long
		/// </param>
		/// <param name="type">desired item type: must be null or xs:integer or a subtype
		/// of xs:integer.
		/// </param>
		/// <returns> an Item of the integer sub-type specified
		/// </returns>
		/// <throws>  EvaluationException if the type is not a subtype of xs:integer. </throws>
		Item CreateItem(long value_Renamed, ItemType type);
		
		/// <summary> Creates a Document Node item by parsing a document.</summary>
		/// <param name="source">a SAX input source
		/// </param>
		/// <returns> a Node item
		/// </returns>
		/// <throws>  EvaluationException wraps a parsing exception </throws>
		/// <throws>  java.io.IOException if the source cannot be read </throws>
		Item CreateItem(XmlSource source);
		
		/// <summary> Creates a Node item by reading a XML stream.
		/// <p>
		/// The resulting item can be any kind of node, depending on the XML
		/// event(s) encountered.
		/// <p>
		/// The source will be read until a complete Node is formed, but no further.
		/// Therefore it is possible to call repeatedly this method on the same
		/// source, provided it is correctly positioned initially.
		/// </summary>
		/// <param name="source">a XML pull stream
		/// </param>
		/// <returns> a Node item
		/// </returns>
		/// <throws>  EvaluationException </throws>
		Item CreateItem(XMLPullStream source);
		
		/// <summary> Creates a copy of the specified Sequence.</summary>
		/// <param name="sequence">an input sequence of items. The position is left
		/// untouched
		/// </param>
		/// <returns> a copy of the input sequence, at position 0
		/// </returns>
		/// <throws>  EvaluationException if the enumeration of the input sequence </throws>
		/// <summary>         caused an error
		/// </summary>
		ItemSequence CopySequence(ItemSequence sequence);
		
		/// <summary> Creates a sequence from a Java object.
		/// <ol>
		/// <li>A null object converts to an empty sequence.
		/// <li>If the type is non-null, it will be used as an indication of the
		/// result type:
		/// <ul>
		/// <li>A type equivalent to xdt:wrappedObject will produce a sequence made
		/// of a single item (the wrapped object) whether it is an array or not.
		/// <li>Otherwise if the object is an array, a <b>java.util.Iterator</b>,
		/// a <b>java.util.Enumeration</b>, or a <b>java.util.Collection</b>, the
		/// method builds a sequence by converting each element of the
		/// array/collection etc. as per {@link #createItem(Object, ItemType)},
		/// using the specified type. For example if the type argument is
		/// xs:double*, the method will attempt to convert each item to a double.
		/// <li>Otherwise (not enumerable) the resulting sequence will have one
		/// item obtained by converting the object to the specified <i>item type</i>.
		/// For example, passing a java.lang.String with a type xs:double, (or
		/// xs:double?, xs:double*, xs:double+) generates a single item sequence,
		/// where the item is obtained by converting the string to a double.
		/// </ul>
		/// <li>If the type is null, it will be inferred from the actual type of
		/// the object. If the object is an array, the type will be
		/// <i>component_type</i>*, where component_type is the mapping of the
		/// array component type. For example, the type for an object of type
		/// String[] will be xs:string*. <br>
		/// If the object is a collection/iterator, the type is item()*. <br>
		/// Then the conversion proceeds like in case 2.
		/// </ol>
		/// 
		/// </summary>
		/// <param name="object">Java object to convert
		/// </param>
		/// <param name="type">optional type hint
		/// </param>
		/// <returns> a sequence of Items.
		/// </returns>
		/// <throws>  EvaluationException </throws>
		ItemSequence CreateSequence(System.Object object_Renamed, ISequenceType type);
	}
}